Important: When updating your code from a previous version of the framework, you definitly need to make sure that you update your copy of the file "MyConfiguration.h" to include all the new configuration options. If you don't, various bits of code simply won't be compiled/included in your application!
Also make sure you add new files (where appropriate) in the release to your project files! Otherwise you may be missing crucial resources or functions.
1.0 beta 14 - Friday, April 12, 1996
IMPORTANT: Many of you are going to wonder what 'p_export' means. I'm using it to export functions using Pascal calling format - only when the framework is being compiled with Pascal support. If you have not turned on Pascal support in "MyConfiguration.h" 'p_export' will be #defined to be nothing - absolutely no effect (as if it didn't exist) - so please just ignore it's presence since it will mean absolutely nothing to the majority of you framework users. (further details on Pascal support are in the version notes below).
I've made numerous little fixes throughout the source files, some of which I forgot to document here (but those are insignificant little changes which won't affect the code's compiling).
* CGI Utilities
- Renamed 'CGIDecodeSpecialChars' and 'CGIEncodeSpecialChars' to 'CGIDecodeURLChars' and 'CGIEncodeURLChars'.
- 'CGIEncodeURLChars' now takes a 'const char *' instead of a 'char *'. A new 'OSErr *' parameter may be NULL if you don't want the err result (from memory allocation). The function has been heavily rewritten to allocate exactly the right amount of space for the new string, instead of growing and shrinking the pointer as it goes along. It also uses pointers instead of offsets. These changes should dramatically improve its performance and stability. (I hope ;-)
- New function: 'CGICharWillHex' returns true if theChar will be converted to hex when encoding as an URL string. With this, I've changed what qualifies as a non-hex encoding character from just alpha-numeric to include the characters: ?, @, -, ., /, :, ", #, $, &, ', and =. (commas are still hex encoded).
- Fixed some bad handle locking in 'cgiAEComplete'.
- Took out the Yield call at the end of 'CGIAESearchDoc'.
- New function 'CustomCGIPostProcess' in "MyCGIProcess.c". Allows for further processing of a CGI event after the result has been returned to the server.
- Switched a bunch of the string parameters in the CGI Record structure to use their max values rather than having to allocate string pointers.
- got rid of the version in the CGI Record structure since it isn't actually a parameter of the CGI event.
* Logging
Note that the logging files were just quickly thrown together. A number of additional functions need to be added, as well as cleaning up of the existing functions. Top on this list is producing MacHTTP/WebSTAR style log entries (date, time, etc.).
- New files "LogUtil.c" & "LogUtil.h"
- Added needed log file management calls to 'StartupApplication' and 'doIdle' ("EventUtil.c")
- New configuration option 'kCompileWithDebugLogging'. Will activate a number of calls to 'LogStringDebug' which may be helpful for debugging purposes. This includes listing the parameters received for a CGI event, and the start and finish times for the CGI event (in ticks).
- New configuration option 'kCompileWithErrorLogging'. When this is on, error messages will be logged (ErrorSystem, ErrorStartup).
- 'my_assert' now calls 'LogStringDebug' if debug logging is on.
- The resource TNAM #3002 "Log File Creator" determines the creator type of the log file. If the resource is not present, the creator type will default to 'ttxt' - SimpleText. This resource should eventually be moved to a preferences file (hopefully within the next beta or two).
* Files
- New files "FileUtil.c" & "FileUtil.h"
- New function 'ResolveAliasFileMountOption' allows the resolving of Finder alias files while preventing the appearance of the 'mount remote volume' interface that can lock up the machine. Use this function instead of the toolbox call 'ResolveAliasFile'.
* Process
- New functions: 'ProcessSleepDefault' and 'ProcessSleepBusy'. Changes the amount of time given to other applications during 'WaitNextEvent' calls and such. These functions change gSleepTicks. You can use these if you want to provide a user preference to change the sleep ticks (such a preference is in the long term plans for the cgi framework preferences interface).
- New functions: 'ProcessSleepSetDefault' and 'ProcessSleepSetBusy'. Used to set the amount of time allocated when 'ProcessSleepDefault' and 'ProcessSleepBusy' are called. Theses functions do not change gSleepTicks.
- New local variables 'vSleepTicksDefault' and 'vSleepTicksBusy' (replaces 'gSleepTicksBusy' from "globals.h"). Don't touch these variables - use the 'ProcessSleep...' accessor functions instead.
- Moved process related code from 'StartupApplication' to new function 'ProcessStartup'.
- New function 'ProcessGiveTime'. Calling this will give time for other processes (both internal to the app and other applications) to run. If thread manager is available, it will just call ThreadYield, otherwise it will call WNE to give time to other applications. You will generally want to call this instead of ThreadYield.
- New constant 'ProcessIsBackgroundOnly'. Will tell you whether the application is a background-only application (faceless).
- Fixed 'ProcessWaitUntilFront' and 'ProcessIsFront' to immediately return false when application is compiled as background only.
- New functions 'ProcessIsMoreBusy' and 'ProcessIsLessBusy'. These set the 'busy' level of the application, which affects how much time it will try to grab for processing.
* Threading
- Added 'WaitNextEvent' call to 'ThreadFinishAllSubThreads' when giving time for other threads to complete.
- New function: 'ThreadYield' should be called in place of 'YieldToAnyThread'. Calls to 'YieldToAnyThread' in the framework have been replaced.
- Moved 'startupThreads' from "Startup.c" to 'ThreadStartup' in "ProcessUtil.c".
- New global variable 'gThreadQuit' is set true when threads should try to quit.
* Deferred Tasks
- New configuration option 'kCompileWithDeferredTask'. Must be set on if you want to use deferred tasks.
- New custom function (one you modify) 'CustomDeferredTask' in "MyHandlers.c" (prototype is in "ProcessUtil.h").
- If you are using Deferred Tasks, 'kStartupThreadsPreallocate' MUST be greater than or equal to one since the deferred task thread uses one preallocated thread. Take this into account when deciding how many threads to preallocate if you preallocate threads for other purposes. Keep in mind that each thread adds about 24k to the application's memory requirements.
* Function Name Changes
Most of the 'My...' functions were renamed at the request of users of the framework. If you want to just use the new names, please ensure that you have set 'kCompileWithout_MY_Names' on (1) in "MyConfiguration.h". If you want to continue to use the old names, set 'kCompileWithout_MY_Names' off (0).
This list has the old name followed by the new name.
- 'MyGotRequiredParams' 'AEFuncGotRequiredParams'
- 'MyAEIdleFunc' 'AEFuncAEIdleFunc'
- 'MyOpenDocument' 'CustomOpenDocument'
- 'MyCGIProcess' 'CustomCGIProcess'
- 'MyCGIStartup' 'CustomCGIStartup'
- 'MyCGIQuit' 'CustomCGIQuit'
- 'MyKeyPress' 'CustomKeyPress'
- 'MyDoStartDrag' 'CustomDoStartDrag'
- 'MyListSTARProcess' 'CustomListSTARProcess'
- 'MyListSTARStartup' 'CustomListSTARStartup'
- 'MyNewHandle' 'MemoryNewHandle'
- 'MyNewHandleClear' 'MemoryNewHandleClear'
- 'MyNewPtr' 'MemoryNewPtr'
- 'MyNewPtrClear' 'MemoryNewPtrClear'
- 'MyGrowZone' 'memoryGrowZone' (now a local-only function in "MemoryUtil.c")
- 'MyNewThreadFromPool' 'ThreadNewThreadFromPool'
- 'myThreadTermination' 'threadTermination'
- 'MyQuit' 'CustomQuit'
- 'MyStartup' 'CustomStartup'
- 'MyCloseWindow' 'CustomCloseWindow'
- 'MyActivateWindow' 'CustomActivateWindow'
- 'MyUpdateWindow' 'CustomUpdateWindow'
- 'MyClickInWindow' 'CustomClickInWindow'
* Configuration
- New option 'kCompileWithout_MY_Names'. If you don't want to support the old function names that began with 'My', then turn this option on. The names were changed because people were wanting to keep the 'My' namespace for their custom code.
* Symantec Support
- Defined 'qd' in "globals.h" for Symantec Project Manager PowerPC compiler only since 'qd' is not defined automatically with that compiler.
* Codewarrior Support
- Add "console.stubs.c" to Codewarrior 8 projects.
- Moved profiler code from "main.c" to "CGI.c"
* Memory Handling
- new constant in "MemoryUtil.h": 'kMemoryHandleLockedFlag' used with HGetState to determine if a Handle is already locked. Does anyone know of an already defined variable in the Universal Headers that means the same thing? I looked in Memory.h, but couldn't find anything like it.
- Some new assertions in front of calls to HLock (& HLockHi) to ensure the Handle isn't already locked.
* About Box (InternetConfig clickable URL)
- New configuration option 'kCompileWithAboutURL'. When set on, the about box will contain a 'clickable-url' for your cgi home-page (or whatever you set it to be). Use the first string in 'STR#' 3002 "URLs" to set the url to use. This requires InternetConfig 1.1 or later. The 'kCompileWithModelessDialogs' configuration option must be on for this to work.
- You will probably want to move the "InternetConfig" folder into your Development tools folder (I keep it in my third-party APIs folder). You will then need to set your access paths for your project to include the path to the "InternetConfig" folder.
* Pascal Support
The begining of support for customizing the framework using Pascal is now in place. If you want to use Pascal for the custom functions, you will have to create the equivelants of the files: "MyHandlers.c", "MyCGIProcess.c" and "MyListSTARProcess.c" (the last two are only required if you are creating a CGI or ListSTAR event handler). Currently, you have to mix C and Pascal source files in a project.
In order to be able to be able to call C functions from Pascal source, I've defined the 'p_export' keyword (in "compiler_stuff.h") which will cause many of the C functions to use pascal calling conventions. The Pascal interfaces files are not yet ready (but should be by mid to late April). If you are mixing Pascal and C source files, you need to set on the new configuration option: 'kCompileWithPascalSupport'.
* Scripting
- corrected the "cgi test.txt" sample AppleScript file.
FileUtil.c, FileUtil.h, LogUtil.c, LogUtil.h, and the InternetConfig support files.
* Removed Files
debug.rsrc
1.0 beta 13 - Friday, January 26, 1995
Important: The CGIRecord (CGIHdl) structure has been changed! The responseData field is no longer a 'char *' (Ptr) - it is now a 'Handle'. You must 'MyCGIProcess'. . This change to the framework can be reverted (to support old code) if you turn the 'kCompileWithCGIResponseDataAsHandle' configuration flag off (in "MyConfiguration.h").
* CGI Support
- Added auto decoding, to the script_name parameter, in 'cgiAESearchDocProcess'.
- New function 'CGIPathToMacPath'. Converts a '/' delimited path to a ':' delimited one, and makes sure there's at least one ':' at the start if the path includes folders. The path string passed to this function MUST have an extra byte after its terminating null byte.
- New function 'CGIActionIsCGIorACGI'. Returns true if the action parameter is either CGI or ACGI.
- Fixed sample html string in the 'MyCGIProcess' function. The closing TITLE element was missing the '/' (</TITLE>). Had to add one to the number of the size of the string used for allocating space for the string (was 141, now is 142). Thanks to Scott Taylor for pointing this out.
- New field in the CGIRecord (CGIHdl) structure: 'suspended'. It's a Boolean which indicates whether the AppleEvent, that the CGIRecord is being used for, has been suspended.
- 'CGIAESearchDoc' sets the new 'suspended' field to true if the AESuspendTheCurrentEvent call is successful. It also yields directly to the new thread if the thread is successfully created. (only used if threading)
- Changed the test in 'cgiAESearchDocProcess' (to determine whether to resume the AppleEvent - almost at the end of the function) for whether the cgi is processing in a sub thread to whether the cgi is processing in a suspended AppleEvent.
- I commented out the 'thread' field in the CGIRecord structure since it's not currently being used. It may come back again in the future if there is a need for it.
- Changed CGIrecord (CGIHdl) responseData from 'char *' (Ptr) to 'Handle'. Affected functions: 'cgiAEComplete', 'cgiDisposeHandle' and 'MyCGIProcess'. This can be reverted (to support old code) if you turn the 'kCompileWithCGIResponseDataAsHandle' configuration flag off.
- Fixed bug in 'CGIFormFieldsFindRecord' where it would crash if (*theCGIHdl)->formFields was nil. Thanks for spotting this bug go to Frank Leahy.
- Added an optional (long) 'refCon' field to the CGIrecord (CGIHdl). To use it, you must set 'kCompileWithCGIRefCon' on in "MyConfiguration.h". If you want to link your own data into the CGIHdl, use the 'refCon' field to store it (or a reference to it). Currently, I don't touch it, so you're responsible for disposal of any memory you allocate for the 'refCon' field.
- New function 'CGIFormFieldsFindValue' returns a pointer to the string value of a field. This is basically a wrapper function for 'CGIFormFieldsFindRecord'.
- Added vNullString initialization to 'InitCGIUtil'.
* Menus
- Moved menu constant declarations into the individual "Menu___.h" files.
- Updated 'Customizing the Menus' section of the documentation.
- Added support for the Window_Application window type to the 'adjust___Menu' functions for each menu. This should be improved in a future version to call custom user functions so the default menu files don't have to be modified if you need to do something special with your menus & application windows.
- Commented out (redundant?) call to 'adjustMenus' in 'mainEventLoop'.
* Configuration
- New additions to "MyConfiguration.h" are now indicated by "•new•" (without the quotes) in the comments above each addition. This should make it easier to update your configuration files.
- 'kIdleTimeToQuit' specifies the default amount of idle time before the application self quits if 'kCompileWithQuitOnLongIdle' is on.
- Moved 'kStartupThreadsPreallocate' from "Startup.c" to "MyConfiguration.h".
- Fixed missing 'kCompileWithThreadedAppleEvents' in CGI AppleEvent handler.
- Moved 'kSleepTicks' from "constants.h" to "MyConfiguration.h"
- 'kCompileWithCGIResponseDataAsHandle' is for backward compatibility with old code.
- 'kCompileWithCGIRefCon' adds the 'refCon' field to CGIRecord (CGIHdl).
* Windows
- Changed the 'dataHdl' member of the 'windowInfo' struct to be a long instead of a Handle. It has also been renamed to 'data', to reflect the change. The reason for this change is because you can store a Handle as a long integer, but you can't store a long as a Handle and I want to be able to do that. Affected functions: WindowNewSetInfo and WindowNewInfoHdl. The new function 'WindowGetData' should be used in place of 'WindowGetDataHdl' (which works the same as before).
- Changed 'AboutBoxOpen' to use 'WindowNewSetInfo'.
* Resources
- New resource file ":Resources:Menus.rsrc" contains the menu resources that were previously in "essential.rsrc".
- Moved the Assertion alert resources from the "essential.rsrc" file into the new "debug.rsrc"
* Threading
- New global variables 'gThreadSleeper' and 'gThreadSleeperIndex' (initialized in 'startupThreads')
- Changed 'MyNewThreadFromPool' and 'myThreadTermination' to put the current thread to sleep (instead of doing a while loop using YieldToAnyThread) if there aren't enough sub-threads to allocate.
- New function 'EventSpawnAEDispatcherThread' called by 'startupAE'.
* Symantec Project Manager
- Added "ThreadsLib.xcoff" file for PPC compiling. Still getting a link error on the 'qd' global - but I've sent a message to Symatec Tech Support to find out how to fix that. We're almost there!
- Make sure you're using Universal Headers 2.0.1 or later!
* Startup - Fixed a bug in 'startupTrapAvailable'. Identified by Scott Taylor.
- Added some additional error checking to 'StartupApplication'.
- Added some new error strings to 'STR#' 301 'Startup Error Strings' in "essential.rsrc"
* Miscellaneous
- New function 'StringConvertCharToChar'
- New function 'ProcessWaitUntilFront'
- New constant 'kSleepTicksWhenBusy' in "MyConfiguration.h". Used for reducing sleep time when multiple threads are processing. Modified functions 'MyNewThreadFromPool' and 'myThreadTermination' in "ProcessUtil.c".
- Removed unused local variable 'theThread' from 'doHighLevelEvent' in "EventUtil.c"
- 'doMenu' and a few of the functions in "EventUtil.c" now use 'ResetQuitIdleTimer'
- New mailing list: grantcgi-announce@arpp1.carleton.ca
